/*
 * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.lang.annotation;

/**
 * 所有注解类型扩展的公共接口。请注意，手动扩展此接口的接口<i>不会</i>定义注解类型。
 * 另请注意，此接口本身不定义注解类型。
 *
 * 有关注解类型的更多信息可以在 <cite>The Java&trade; Language Specification</cite>
 * 的第 9.6 节中找到。
 *
 * {@link java.lang.reflect.AnnotatedElement} 接口讨论了将注解类型从不可重复
 * 演变为可重复时的兼容性问题。
 *
 * @author  Josh Bloch
 * @since   1.5
 */
public interface Annotation {
    /**
     * 如果指定对象表示逻辑上等价于此注解的注解，则返回 true。
     * 换句话说，如果指定对象是与此实例相同注解类型的实例，
     * 且其所有成员都等于此注解的相应成员，则返回 true，如下所定义：
     * <ul>
     *    <li>两个对应的基本类型成员，其值为 <tt>x</tt> 和 <tt>y</tt>，
     *    如果 <tt>x == y</tt>，则认为相等，除非它们的类型是 <tt>float</tt> 或 <tt>double</tt>。
     *
     *    <li>两个对应的 <tt>float</tt> 成员，其值为 <tt>x</tt> 和 <tt>y</tt>，
     *    如果 <tt>Float.valueOf(x).equals(Float.valueOf(y))</tt>，则认为相等。
     *    （与 <tt>==</tt> 运算符不同，NaN 被认为等于自身，<tt>0.0f</tt> 不等于 <tt>-0.0f</tt>。）
     *
     *    <li>两个对应的 <tt>double</tt> 成员，其值为 <tt>x</tt> 和 <tt>y</tt>，
     *    如果 <tt>Double.valueOf(x).equals(Double.valueOf(y))</tt>，则认为相等。
     *    （与 <tt>==</tt> 运算符不同，NaN 被认为等于自身，<tt>0.0</tt> 不等于 <tt>-0.0</tt>。）
     *
     *    <li>两个对应的 <tt>String</tt>、<tt>Class</tt>、枚举或注解类型成员，
     *    其值为 <tt>x</tt> 和 <tt>y</tt>，如果 <tt>x.equals(y)</tt>，则认为相等。
     *    （请注意，对于注解类型成员，此定义是递归的。）
     *
     *    <li>两个对应的数组类型成员 <tt>x</tt> 和 <tt>y</tt>，
     *    如果 <tt>Arrays.equals(x, y)</tt>，则认为相等，
     *    使用 {@link java.util.Arrays#equals} 的适当重载。
     * </ul>
     *
     * @return 如果指定对象表示逻辑上等价于此注解的注解，则返回 true，否则返回 false
     */
    boolean equals(Object obj);

    /**
     * 返回此注解的哈希码，如下所定义：
     *
     * <p>注解的哈希码是其成员（包括具有默认值的成员）的哈希码之和，如下所定义：
     *
     * 注解成员的哈希码是（成员名称的哈希码乘以 127，由 {@link String#hashCode()} 计算）
     * 异或成员值的哈希码，如下所定义：
     *
     * <p>成员值的哈希码取决于其类型：
     * <ul>
     * <li>基本值 <tt><i>v</i></tt> 的哈希码等于
     *     <tt><i>WrapperType</i>.valueOf(<i>v</i>).hashCode()</tt>，其中
     *     <tt><i>WrapperType</i></tt> 是与 <tt><i>v</i></tt> 的基本类型对应的包装类型
     *     （{@link Byte}、{@link Character}、{@link Double}、{@link Float}、
     *     {@link Integer}、{@link Long}、{@link Short} 或 {@link Boolean}）。
     *
     * <li>字符串、枚举、类或注解成员值 <tt><i>v</i></tt> 的哈希码通过调用
     *     <tt><i>v</i>.hashCode()</tt> 计算。（对于注解成员值，这是一个递归定义。）
     *
     * <li>数组成员值的哈希码通过在值上调用
     *     {@link java.util.Arrays#hashCode(long[]) Arrays.hashCode}
     *     的适当重载来计算。（每种基本类型有一个重载，对象引用类型有一个重载。）
     * </ul>
     *
     * @return 此注解的哈希码
     */
    int hashCode();

    /**
     * 返回此注解的字符串表示形式。表示形式的详细信息依赖于实现，
     * 但以下内容可以视为典型：
     * <pre>
     *   &#064;com.acme.util.Name(first=Alfred, middle=E., last=Neuman)
     * </pre>
     *
     * @return 此注解的字符串表示形式
     */
    String toString();

    /**
     * 返回此注解的注解类型。
     * @return 此注解的注解类型
     */
    Class<? extends Annotation> annotationType();
}
